Colocated documentation

Je suis un adepe du paradigme Monorepo, de la documentation colocalisée et des issues colocalisées.

Je conseille de nommer le repository avec le nom de l'organisation.

Par exemple, si mon organisation se nomme « Dummy Tech » et si elle utilise GitLab, alors je conseille d'utiliser le slug dummy-tech, ce qui donne gitlab.com/dummy-tech/dummy-tech/ et « Dummy Tech Monorepo » comme titre de repository.

La neutralité de ce nom facilite les décisions concernant ce qui peut ou non être inclus dans le repository, sans être limité par un nom trop restrictif. Il est flexible face à l'évolution du projet. Il permet d'éviter bien des débats à propos du nommage.

En 2018, sur GitHub, j'ai découvert un exemple de monorepo d'une organisation. Cet exemple m'a servi de base et je l'ai fait évoluer quand je travaillais chez Spacefill.

Voici un exemple d'arborescence de monorepo que j'aime utiliser :

dummy-tech
├── deployments
│   ├── prod
│   └── sandbox
├── ci
├── docs
├── playgrounds
│   ├── playground_a
│   └── playground_b
├── services
│   ├── service_a
│   ├── service_b
│   └── service_c
└── tools
    ├── tool_a
    ├── tool_b
    └── tool_c

J'ai relu cette note de David Larlet :

Silk = documentation et tests

Markdown based document-driven web API testing.

Silk

La rapidité d’exécution d’un outil écrit en Go est toujours surprenante, j’ai eu besoin de vérifier que les tests étaient bien passés pour être sûr de son bon fonctionnement… Mon expérience me montre qu’une documentation qui n’est pas testée/proche du code n’est jamais synchronisée et conduit à des frustrations pour les utilisateurs. Silk est un moyen de faire cela directement depuis votre markdown, ça me rappelle d’une certaine manière le couple docutils/reStructuredText. En rapide. Et je ne saurais trop insister sur l’importance d’avoir une suite de tests rapide pour qu’elle reste pertinente.

Raconter une histoire dans vos tests est plus verbeux mais assurément plus intéressant pour la personne qui cherchera à comprendre ce que vous avez implémenté. Il y a de grandes chances que ce soit vous. Le README du dépôt est un exemple de ce qui peut être réalisé.

-- 25 février 2016

Je pense que ce billet a participer à ma sensibilitasion à la notion de colocated documentation.